WIDGET_WINDOW

The WIDGET_WINDOW function creates a graphics widget.

Example

The following lines create a simple widget application. For a more complete example, see the end of this topic.

; Create the widgets.

wBase = WIDGET_BASE(/COLUMN)

wDraw = WIDGET_WINDOW(wBase, X_SCROLL_SIZE=400, Y_SCROLL_SIZE=400)

WIDGET_CONTROL, wBase, /REALIZE

 

; Retrieve the newly-created Window object.

WIDGET_CONTROL, wDraw, GET_VALUE=oWin

 

; Make sure this is the current window

oWin.Select

 

p = PLOT(/TEST, /CURRENT, /FILL_BACKGROUND)

Syntax

Result = WIDGET_WINDOW(Parent [, DRAG_NOTIFY=string] [, /DROP_EVENTS] [, EVENT_FUNC=string] [, EVENT_HANDLER=objref] [, FRAME=integer] [, GROUP_LEADER=widget ID] [, IGNORE_ACCELERATORS=value] [, KEYBOARD_HANDLER=function] [, KILL_NOTIFY=string] [, MOUSE_DOWN_HANDLER=function] [, MOUSE_MOTION_HANDLER=function] [, MOUSE_UP_HANDLER=function] [, MOUSE_WHEEL_HANDLER=function] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, RENDERER={0|1}] [, RESOURCE_NAME=string] [, SELECTION_CHANGE_HANDLER=function] [, SENSITIVE=0] [, TOOLTIP=string] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0|1|2}] [, UVALUE=variable] [, X_SCROLL_SIZE=value] [, Y_SCROLL_SIZE=value] [, XSIZE=value] [, YSIZE=value] [, XOFFSET=value] [, YOFFSET=value])

Return Value

The returned value of this function is the widget ID of the newly-created widget.

Arguments

Parent

The widget ID of the parent widget.

Keywords

Keywords are applied only during the initial creation of the graphic.

DRAG_NOTIFY

Set this keyword equal to a string containing the name of a function that will be automatically called as the end-user drags over the widget. Alternatively, set this keyword equal to the string <default> (including the < and > characters) to use the system default callback. See the WIDGET_DRAW routine for details on using this keyword.

DROP_EVENTS

Use this keyword to specify whether or not the widget will generate drop events when the user drags an item onto the draw area with the mouse cursor and releases the mouse button. A value of 1 (one) causes the widget to generate drop events and a value of 0 (zero) causes the widget to not generate drop events. The default is to not generate drop events. Specifying a DRAG_NOTIFY callback does not affect a widget’s ability to generate drop events. See the WIDGET_DRAW routine for details on using this keyword.

EVENT_FUNC

A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget.

EVENT_HANDLER

Set this property to an object reference to be used when events are received by the window. The object must be a subclass of GraphicsEventAdapter. See Creating an Event Handler Class to Control Events for details on how to write this object class.

Note: The EVENT_HANDLER class is intended to be a convenient alternative to the procedural event handlers. If you specify both the EVENT_HANDLER property and an event handler function (MOUSE_DOWN_HANDLER for example), then the object method will be called first. If the object method returns a value of 1, then execution will continue and the handler function will then be called. If the object method returns 0, then the handler function will not be called and the default event handling will also be skipped.

FRAME

The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a hint to the toolkit, and may be ignored in some instances.

GROUP_LEADER

The widget ID of an existing widget that serves as “group leader” for the newly-created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed.

A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group.

IGNORE_ACCELERATORS

Set this keyword to specify what WIDGET_BUTTON accelerators are to be ignored when this graphics widget has keyboard focus. Setting IGNORE_ACCELERATORS allows a defined list of accelerators to be processed by the graphics widget instead of by the conflicting accelerated button. Valid values are:

Ordinarily, accelerators are processed before keyboard events reach the widget that has the keyboard focus. Setting IGNORE_ACCELERATORS allows a defined list of accelerators to be processed by the graphics widget instead of by associated buttons or menu items. Once the graphics widget loses focus, all specified accelerators are automatically re-enabled.

See Disabling Button Widget Accelerators for usage details and examples.

KEYBOARD_HANDLER

Set this property to the name of a function that will be called when a key is pressed or released. See Creating Keyboard Event Functions for details on how to write these functions.

Tip: Instead of writing separate functions for each of the event handlers, you may find it convenient to create a single object class and use the EVENT_HANDLER property instead.

KILL_NOTIFY

Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such “callback” procedure. It can be removed by setting the routine to an empty string ('').

The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called.

MOUSE_DOWN_HANDLER

Set this property to the name of a user-defined function that is called when the mouse button is pressed.

MOUSE_MOTION_HANDLER

Set this property to the name of a user-defined function that is called when the mouse is moved.

MOUSE_UP_HANDLER

Set this property to the name of a user-defined function that is called when the mouse button is released.

MOUSE_WHEEL_HANDLER

Set this property to the name of a user-defined function that is called when the mouse wheel is moved.

Note: See Creating Functions to Control Mouse Events for details on how to write the mouse event functions.

Tip: Instead of writing separate functions for each of the mouse event handlers, you may find it convenient to create a single object class and use the EVENT_HANDLER property instead.

NO_COPY

Set this keyword to 1 to take the data away from the UVALUE variable and attach it directly to the widget. After the WIDGET_WINDOW function returns, the UVALUE variable will then be undefined. This keyword is ignored if UVALUE is not present.

NOTIFY_REALIZE

Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such “callback” procedure. The callback routine is called with the widget ID as its only argument.

RENDERER

Set this keyword to an integer value indicating which graphics renderer to use when drawing objects within the window. Valid values are:

By default, your platform’s native OpenGL implementation is used. If your platform does not have a native OpenGL implementation, IDL’s software implementation is used regardless of the value of this property.

RESOURCE_NAME

A string containing an X Window System resource name to be applied to the widget. See RESOURCE_NAME for a complete discussion of this keyword.

SELECTION_CHANGE_HANDLER

Set this property to the name of a function that is called when a graphic is selected or deselected. See  Creating Selection Change Event Handlers for details on how to write these functions.

Tip: Instead of writing separate functions for each of the event handlers, you may find it convenient to create a single object class and use the EVENT_HANDLER property instead.

SENSITIVE

Set this keyword to 0 to turn off all event processing for the widget. The default is 1, which enables all event processing. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure.

TOOLTIP

Set this keyword to a string that will be displayed when the cursor hovers over the widget. For UNIX platforms, this string must be non-zero in length.

TRACKING_EVENTS

Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see TRACKING_EVENTS in the documentation for WIDGET_BASE.

UNAME

Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.

To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.

UNITS

Set this keyword to specify the units used when supplying measurements or position values. Set UNITS equal to 0 to specify that all measurements are in pixels (this is the default), to 1 to specify that all measurements are in inches, or to 2 to specify that all measurements are in centimeters. This keyword does not change the units used in a widget event structure or in most of the fields of the geometry structure returned by WIDGET_INFO.

UVALUE

The “user value” to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. If UVALUE is not present, the widget’s initial user value is undefined.

X_SCROLL_SIZE

The width of the widget in units specified by the UNITS keyword (pixels are the default). By default X_SCROLL_SIZE is set equal to XSIZE.

Y_SCROLL_SIZE

The height of the widget in units specified by the UNITS keyword (pixels are the default). By default Y_SCROLL_SIZE is set equal to YSIZE.

XSIZE

The width of the graphics window (the drawing area) in units specified by the UNITS keyword (pixels are the default). If XSIZE is larger than X_SCROLL_SIZE then scroll bars will be automatically added. By default, XSIZE is set equal to X_SCROLL_SIZE. If neither XSIZE nor X_SCROLL_SIZE is passed in, then the width is set to 640 pixels.

YSIZE

The height of the graphics window (the drawing area) in units specified by the UNITS keyword (pixels are the default). If YSIZE is larger than Y_SCROLL_SIZE then scroll bars will be automatically added. By default, YSIZE is set equal to Y_SCROLL_SIZE. If neither YSIZE nor Y_SCROLL_SIZE is passed in, then the height is set to 512 pixels.

XOFFSET

The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent.

Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout.

YOFFSET

The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget.

Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout.

Keywords to WIDGET_CONTROL

A number of keywords to the WIDGET_CONTROL procedure affect the behavior of graphics widgets. In addition to those keywords that affect all widgets, the following are particularly useful: DRAW_XSIZE, DRAW_YSIZE, GET_DRAW_VIEW, GET_VALUE, IGNORE_ACCELERATORS, INPUT_FOCUS, SET_DRAW_VIEW, TOOLTIP.

Keywords to WIDGET_INFO

A number of keywords to the WIDGET_INFO function return information that applies specifically to graphics widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: GEOMETRY, TOOLTIP.

Example

The following example creates an IDL widget application with a main graphics window, and a status bar at the bottom. When you move the mouse around the window, the X and Y locations are displayed in the status bar.

Save all of the following code into a file named "widget_window_ex.pro". Then, from within IDL, compile and run the code.

;+

; The event handler called when any mouse button is pressed.

;-

FUNCTION WIDGET_WINDOW_EX_MOUSE_DOWN_EVENT, $

win, x, y, button, keymods, clicks

COMPILE_OPT idl2

 

state = win.uvalue

IF(button eq 1 && keymods eq 2) then begin

state['drag'] = 1

state['start'] = [x,y]

; Do not do the default handling.

RETURN, 0

ENDIF

; Continue with the default handling.

return, 1

END

 

;+

; The event handler called when any mouse button is released.

;-

FUNCTION WIDGET_WINDOW_EX_MOUSE_UP_EVENT, win, x, y, button

COMPILE_OPT idl2

state = win.uvalue

state['drag'] = 0

RETURN, 1

END

 

;+

; The event handler called when the mouse is moved.

;-

FUNCTION WIDGET_WINDOW_EX_MOUSE_MOTION_EVENT, win, x, y, keymods

COMPILE_OPT idl2

 

state = win.uvalue

IF(state['drag']) then begin

difference = [x,y] - state['start']

new_center = state['center'] + difference[0]

new_width = state['width'] + difference[1]

new_brain = SET_WINDOW(state['image'], new_center, new_width)

win['display'].setdata, new_brain

return, 0

ENDIF

RETURN, 1

END

 

;+

; Helper routine. Sets window center and width for an image.

;-

FUNCTION SET_WINDOW, image, center, width

COMPILE_OPT idl2

lo = center - 0.5*width

hi = center + 0.5*width

RETURN, BYTSCL((image > lo) < hi)

END

 

;+

; The launch routine. Sets up UI & state variable, loads data.

;-

PRO WIDGET_WINDOW_EX

COMPILE_OPT idl2

 

; An MR image with center and width.

brain = READ_IMAGE(FILE_WHICH('mr_brain.dcm'))

center = 1011 ; from file

width = 2021 ; from file

brain_scaled = SET_WINDOW(brain, center, width)

 

wtop = WIDGET_BASE(/COLUMN, $

TITLE='Graphics event handling with IDL widgets')

wdraw = WIDGET_WINDOW(wtop, $

MOUSE_DOWN_HANDLER='widget_window_ex_mouse_down_event', $

MOUSE_UP_HANDLER='widget_window_ex_mouse_up_event', $

MOUSE_MOTION_HANDLER='widget_window_ex_mouse_motion_event')

WIDGET_CONTROL, wtop, /REALIZE

 

; Extract the window reference from the draw widget,

; and display the first image resampled to 150% original size.

WIDGET_CONTROL, wdraw, GET_VALUE=w

g = IMAGE(brain_scaled, /CURRENT, TITLE='MR: Brain', NAME='display')

g.SCALE, 1.5, 1.5, 1.0

 

t = TEXT(0.5,0.02, $

['Hold <Ctrl> and drag horizontally to change brightness,', $

'drag vertically to change contrast'], $

ALIGNMENT='center')

 

; Make a state variable.

state = HASH()

state['image'] = brain_scaled

state['drag'] = 0

state['start'] = [0,0]

state['center'] = center

state['width'] = width

 

; Attach the state variable to the window's user value. Attach the

; window to the top-level base's user value. This ensures that state

; information can be communicated to both the widget and event handlers.

w.uvalue = state

WIDGET_CONTROL, wtop, SET_UVALUE=w

 

XMANAGER, 'widget_window_ex', wtop, /NO_BLOCK

END

Version History

8.0

Introduced
8.1 Added the following properties: KEYBOARD_HANDLER, MOUSE_DOWN_HANDLER, MOUSE_MOTION_HANDLER, MOUSE_UP_HANDLER, MOUSE_WHEEL_HANDLER, SELECTION_CHANGE_HANDLER
8.2 Remove the following properties: BUTTON_EVENTS, EXPOSE_EVENTS, KEYBOARD_EVENTS, MOTION_EVENTS, VIEWPORT_EVENTS, WHEEL_EVENTS.
8.2.1

Properties added: EVENT_HANDLER

See Also

!COLOR, WIDGET_DRAW, WINDOW